Some changes occurred in HTML/CSS/JS.

cc @GuillaumeGomez

Just a quick message to say that I think that the layout is (with your changes) even more confusing. I don't know where I should put my eyes. The variant name is so big that it's disturbing, I feel that I should stop at every single of them. The all "Variant" layout feels out of place with the rest of the documentation.

Maybe instead of putting the variant name in h{3,4} you could make it bolder, this would would accentuate the difference but not be as disturbing as your changes.

Great feedback, thanks. I'm keeping the h3 / h4 (since that's a structural, not a display issue) but I adjusted the CSS to match your recommendation: now both h3 and h4 for variants are font-size: 16, but h3 is font-weight: 600. This is nicely consistent with how we render method headings.

Updated the demos.

Can you add a demo for what it looks like when some of the fields have documentation?

I updated the xmlparser / Token demo to include documentation on the fields:

https://jacob.hoffman-andrews.com/rust/xmlparser-updated/xmlparser/enum.Token.html#variants

One thing I'd suggest is to add a bit more space between the variant heading and "Fields" and between the fields and the variant's docs. Right now it looks a bit cramped to me.

Happy to do so! Would you mind trying out some spacing options in your developer tools and suggesting one that looks good to you? I'm happy to keep iterating on this but I suspect we'll save some round trips this way. :-)

Nice, way better.

One thing, it think you can completely remove the "Fields" title (we can clearly tell that they are fields). This would look like this:

This would simplify the layout to only let the important information.

One thing, it think you can completely remove the "Fields" title (we can clearly tell that they are fields).

I was going to suggest this, but one problem is that for tuple fields, the docs might be confusing. The fields aren't actually named 0, 1, etc., but if you remove that heading, there's no indication that they belong to a tuple variant.

The diff from my changes:

- .sub-variant > span {
-    margin-left: 20px;
- }

  .sub-variant {
     margin-left: 24px;
-    margin-bottom: 10px;
+    margin-bottom: 15px;
  }

plus the removal of the h4 "Fields".

One thing, it think you can completely remove the "Fields" title (we can clearly tell that they are fields).

I was going to suggest this, but one problem is that for tuple fields, the docs might be confusing. The fields aren't actually named 0, 1, etc., but if you remove that heading, there's no indication that they belong to a tuple variant.

Currently they are, so I don't see this as an issue.

@jsha: I find it harder to read the documentation because it's actually not that easy to find where the field starts and where its documentation starts.

I've updated the CSS like so:

• More vertical separation between variant name and the "Fields" heading.
• More vertical separation between the bottom of the variant's fields and the beginning of the variant's documentation.
• Leftward indentation is bigger and more consistent with what we do elsewhere: 24px.

I think this should improve visual distinctiveness between the bottom of the fields and the beginning of the doccomment. I don't want to remove the "Fields" heading right now, since I think it is important for explaining the section it comes in front of.

Also I'd like to point out this is intended to be a quick fix for some significant problems with the display of enum field variants (horizontal line inverts the hierarchy; fields show up below doccomment; fields heading is bold, inverting the hierarchy). I always want to try and get the details right, of course, but I also don't want to let a few pixels of whitespace take up too much time here - there are other big display issues I'd like to move on to fixing, also.

I was going to suggest this, but one problem is that for tuple fields, the docs might be confusing. The fields aren't actually named 0, 1, etc., but if you remove that heading, there's no indication that they belong to a tuple variant.

Currently they are, so I don't see this as an issue.

What do you mean by "currently they are"? The issue I was describing is that in the docs, the fields are displayed as 0: etc., which makes it look like the variant was defined as Variant { 0: i32 }, which is invalid syntax. That's why it seems potentially useful to keep the "Tuple Fields" header, to make it clear that it's actually a tuple variant.

I've updated the CSS like so: [...]

Ah, this looks much better, thank you! After this change, the docs feel much less cramped to me. I only have two remaining comments about the UI (haven't looked at the impl yet):

• Putting the fields before the variant's doc-comment seems like it could be confusing. The variant's docs are the summary, while the fields are the details; and in general, one would not put the summary after the details. Can you explain your rationale for this change? I feel that it might be best to leave it as-is for now and just make the heading, spacing, etc. improvements. That way we can make incremental progress without this PR getting stalled on other parts of the change.

• I think the visual hierarchy would be a bit clearer if the font-size of the variant's name were increased from 1em to 1.1em. What do you think? It looks like this if I edit in devtools:

  

Putting the fields before the variant's doc-comment seems like it could be confusing. The variant's docs are the summary, while the fields are the details; and in general, one would not put the summary after the details. Can you explain your rationale for this change?

In other places, the doccomment is always the last part of a section, and fields / other generated stuff is at the top. Consider the top of the page, for instance - it has struct contents, or enum contents, and then the doccomment underneath. However, I don't feel strongly about this, so I've reverted to the previous behavior of fields on the bottom.

I've also updated the font sizes as you suggest, and pushed the demos.

I'm realizing now that the [+]/[-] symbols are actually great helper to identify item vs documentation... With just playing on the separation, it's not enough (at least not for me).

Can we have a symbol or symbol or something making it easier to spot the fields?

Can you tell me more about what you mean by "identify item vs documentation?" Are you saying that the "Fields" heading and the lines below it look like they are prose documentation written by the doc author? Or that you're scanning the docblock looking for the break between prose and Rusty items, and finding that the break doesn't catch the attention enough?

Or that you're scanning the docblock looking for the break between prose and Rusty items, and finding that the break doesn't catch the attention enough?

I meant that. It's hard to know if I'm still reading documentation or if it's a field. I have to stop and look a bit around to have this answer, which is not great.

I'm realizing now that the [+]/[-] symbols are actually great helper to identify item vs documentation... With just playing on the separation, it's not enough (at least not for me).

Can we have a symbol or symbol or something making it easier to spot the fields?

Would moving the fields docs to right below the variant's name like they were earlier in this PR make it easier for you? I agree that the fields look a bit like they're part of the docs themselves. I'd rather put the fields above the variant's docs than add more symbols to the docs though.

Worth a try!

Before I go back to that, I have one more idea to try:

This increases the font-weight on Fields to 500, and changes the color to blue. That matches the styling we use for Markdown prose headings elsewhere. Note: The blue indicates a hyperlink, so if we proceed with this I'll change Fields to be a hyperlink that points to its own anchor, the same as other prose headings.

If this is not satisfactory I'm perfectly happy going back to fields-on-top. Let me know which you prefer!

This increases the font-weight on Fields to 500, and changes the color to blue. That matches the styling we use for Markdown prose headings elsewhere. Note: The blue indicates a hyperlink, so if we proceed with this I'll change Fields to be a hyperlink that points to its own anchor, the same as other prose headings.

I think this adds more complexity and actually makes the docs more confusing. The issue is that "Fields" looks like it's part of the prose, and this makes it look even more like it's part of the prose. Also, I think we should be leaning away from adding more colors and links to the docs.

Good point, thanks. Back to fields-on-top. Demos updated - don't forget to hard-refresh.

☔ The latest upstream changes (presumably #90422) made this pull request unmergeable. Please resolve the merge conflicts.

(I'll try to review this soon.)

Looks good to me as well. Once we have confirmation for @camelid's last message, we can approve it. :)

Once #90089 (comment) is addressed, r=camelid,GuillaumeGomez :)

@bors r=camelid,GuillaumeGomez rollup

📌 Commit 69df43b has been approved by camelid,GuillaumeGomez

Thanks again for making this great UI improvement!